.TH std::common_iterator 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::common_iterator \- std::common_iterator

.SH Synopsis
   Defined in header <iterator>
   template< std::input_or_output_iterator I, std::sentinel_for<I> S >

       requires ( !std::same_as<I, S> && std::copyable<I> )             \fI(since C++20)\fP

           class common_iterator;

   std::common_iterator is an iterator I / sentinel S adaptor that may represent a
   non-common range (where the types of I and S differ) as a common_range, by
   containing either an iterator or a sentinel, and defining the appropriate equality
   comparison operators operator==.

   std::common_iterator can be used as a "bridge" between sequences represented by
   iterator/sentinel pair and legacy functions that expect common_range-like sequences.

.SH Member functions

   constructor     constructs a new iterator adaptor
   (C++20)         \fI(public member function)\fP
   operator=       assigns another iterator adaptor
   (C++20)         \fI(public member function)\fP
   operator*       accesses the pointed-to element
   operator->      \fI(public member function)\fP
   (C++20)
   operator++      advances the iterator adaptor
   operator++(int) \fI(public member function)\fP
   (C++20)

.SH Non-member functions

   operator== compares the underlying iterators or sentinels
   (C++20)    \fI(function template)\fP
   operator-  computes the distance between two iterator adaptors
   (C++20)    \fI(function template)\fP
   iter_move  casts the result of dereferencing the underlying iterator to its
   (C++20)    associated rvalue reference type
              \fI(function)\fP
   iter_swap  swaps the objects pointed to by two underlying iterators
   (C++20)    \fI(function template)\fP

.SH Helper classes

                                                   computes the associated difference
   std::incrementable_traits<std::common_iterator> type of the std::common_iterator
   (C++20)                                         type
                                                   \fI(class template specialization)\fP

                                                   provides uniform interface to the
   std::iterator_traits<std::common_iterator>      properties of the
   (C++20)                                         std::common_iterator type
                                                   \fI(class template specialization)\fP


.SH Example


// Run this code

 #include <algorithm>
 #include <iostream>
 #include <iterator>
 #include <list>
 #include <string>

 template<class ForwardIter>
 void fire(ForwardIter first, ForwardIter last)
 {
     std::copy(first, last, std::ostream_iterator<std::string>{std::cout, " "});
 }

 int main()
 {
     std::list<std::string> stars{"Pollux", "Arcturus", "Mira", "Aldebaran", "Sun"};

     using IT = std::common_iterator<
                    std::counted_iterator<std::list<std::string>::iterator>,
                    std::default_sentinel_t>;

     fire(IT(std::counted_iterator(stars.begin(), stars.size() - 1)),
          IT(std::default_sentinel));
 }

.SH Output:

 Pollux Arcturus Mira Aldebaran

.SH References

     * C++23 standard (ISO/IEC 14882:2023):

     * 23.5.5 Common iterators [iterators.common]
     * C++20 standard (ISO/IEC 14882:2020):

     * 23.5.4 Common iterators [iterators.common]

.SH See also

   ranges::common_range specifies that a range has identical iterator and sentinel
   (C++20)              types
                        (concept)
   ranges::common_view  converts a view into a common_range
   views::common        \fI(class template)\fP (range adaptor object)
   (C++20)
